Skip to content

feat(ai-gemini): stream structured outputs natively - #971

Open
Missing-Identity wants to merge 2 commits into
TanStack:mainfrom
Missing-Identity:feat/gemini-structured-output-stream
Open

feat(ai-gemini): stream structured outputs natively#971
Missing-Identity wants to merge 2 commits into
TanStack:mainfrom
Missing-Identity:feat/gemini-structured-output-stream

Conversation

@Missing-Identity

@Missing-Identity Missing-Identity commented Jul 21, 2026

Copy link
Copy Markdown

What changed

  • add native structuredOutputStream support to the standard Gemini text adapter
  • add native structured-output streaming to the experimental Gemini Interactions adapter
  • accumulate and parse streamed JSON before emitting structured-output.complete
  • preserve interaction ID and run-finished event ordering
  • add focused adapter coverage, enable Gemini in the structured-output-stream E2E matrix, and add a minor changeset

Closes #570.

Validation

  • focused Gemini adapter tests: 46 passed
  • complete @tanstack/ai-gemini test suite: 239 passed
  • @tanstack/ai-gemini TypeScript check: passed
  • @tanstack/ai-gemini ESLint: no errors; seven pre-existing warnings
  • @tanstack/ai-gemini production build: passed
  • git diff --check: passed

Limitations

The hosted environment could not download Playwright Chromium, so browser E2E execution was not claimed. The existing structured-output-stream E2E matrix was updated to include Gemini.

Summary by CodeRabbit

  • New Features
    • Added native structured-output streaming for Gemini text generation.
    • Added structured-output streaming support for the experimental Gemini Interactions API.
    • Streaming now produces a structured-output.complete custom event with the parsed JSON result (plus the original text) before the final completion event.
  • Improved Reliability
    • Enhanced error reporting for empty, truncated, parse-failing, or provider-failing streams.
  • Tests
    • Expanded structured-output streaming end-to-end and adapter test coverage for Gemini.

@coderabbitai

coderabbitai Bot commented Jul 21, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

Warning

Review limit reached

@tombeckenham, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 48 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: ea4f7ec6-e6ef-4f49-83db-20b651a11784

📥 Commits

Reviewing files that changed from the base of the PR and between 888e8b7 and a259d22.

📒 Files selected for processing (6)
  • .changeset/tidy-gemini-streams.md
  • packages/ai-gemini/src/adapters/text.ts
  • packages/ai-gemini/src/experimental/text-interactions/adapter.ts
  • packages/ai-gemini/tests/gemini-adapter.test.ts
  • packages/ai-gemini/tests/text-interactions-adapter.test.ts
  • testing/e2e/src/lib/feature-support.ts
📝 Walkthrough

Walkthrough

Native structured-output streaming was added to the Gemini text and experimental Gemini Interactions adapters. Both accumulate JSON deltas, emit parsed completion events before terminal events, handle stream failures, and add tests plus E2E feature coverage.

Changes

Gemini structured-output streaming

Layer / File(s) Summary
Gemini text streaming
packages/ai-gemini/src/adapters/text.ts, packages/ai-gemini/tests/gemini-adapter.test.ts
GeminiTextAdapter streams JSON responses, emits incremental content, and produces structured-output.complete before RUN_FINISHED, with standardized error events for failures.
Gemini Interactions streaming
packages/ai-gemini/src/experimental/text-interactions/adapter.ts, packages/ai-gemini/tests/text-interactions-adapter.test.ts
GeminiTextInteractionsAdapter streams schema-constrained responses, preserves interaction IDs, parses accumulated JSON, and validates completion ordering and chaining.
Streaming coverage and release metadata
testing/e2e/src/lib/feature-support.ts, .changeset/tidy-gemini-streams.md
Gemini is added to the structured-output-stream feature matrix and the package receives a minor changeset.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant GeminiAdapter
  participant GeminiAPI
  participant Consumer
  Caller->>GeminiAdapter: structuredOutputStream(options)
  GeminiAdapter->>GeminiAPI: Request JSON schema with streaming enabled
  GeminiAPI-->>GeminiAdapter: JSON text deltas
  GeminiAdapter-->>Consumer: TEXT_MESSAGE_CONTENT chunks
  GeminiAdapter-->>Consumer: structured-output.complete
  GeminiAdapter-->>Consumer: RUN_FINISHED
Loading

Possibly related PRs

  • TanStack/ai#587: Updates structured-output custom event typing used by this runtime behavior.
  • TanStack/ai#781: Provides the Interactions API event and response-format migration used by this adapter.
🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly summarizes the main change: native structured output streaming for Gemini adapters.
Description check ✅ Passed The description covers changes, validation, and limitations, though it omits the template checklist and release impact section.
Linked Issues check ✅ Passed The PR implements native structuredOutputStream support, event ordering, tests, and Gemini E2E coverage requested in #570.
Out of Scope Changes check ✅ Passed The added changeset, tests, and E2E matrix update are all directly related to the structured-output streaming work.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/ai-gemini/src/adapters/text.ts`:
- Around line 229-283: The structuredOutputStream method uses inconsistent run
IDs between stream processing and structured-stream errors. Resolve a single
runId, using the existing override-or-generated fallback behavior, create an
options object containing it, and pass that same object to processStreamChunks
and every structuredStreamError call so all emitted events share the resolved
ID.

In `@packages/ai-gemini/tests/gemini-adapter.test.ts`:
- Line 3: Reorder the named imports from `@tanstack/ai` alphabetically to satisfy
ESLint sort-imports in packages/ai-gemini/tests/gemini-adapter.test.ts:3-3 and
packages/ai-gemini/tests/text-interactions-adapter.test.ts:3-3; update only the
import member ordering.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: c313a8d4-d80c-4e8d-a85c-1fc5ab15f7ca

📥 Commits

Reviewing files that changed from the base of the PR and between 7c7aa09 and 35b371e.

📒 Files selected for processing (6)
  • .changeset/tidy-gemini-streams.md
  • packages/ai-gemini/src/adapters/text.ts
  • packages/ai-gemini/src/experimental/text-interactions/adapter.ts
  • packages/ai-gemini/tests/gemini-adapter.test.ts
  • packages/ai-gemini/tests/text-interactions-adapter.test.ts
  • testing/e2e/src/lib/feature-support.ts

Comment thread packages/ai-gemini/src/adapters/text.ts Outdated
Comment thread packages/ai-gemini/tests/gemini-adapter.test.ts Outdated
@tombeckenham

Copy link
Copy Markdown
Contributor

Thanks for the PR, @Missing-Identity! 🙌 @jherr will take a look.

Automated pre-review checks

  • ✅ CI passing
  • ✅ No merge conflicts
  • ✅ Changeset present
  • ✅ E2E test changes included

Automated triage — a human review follows.

@tombeckenham tombeckenham added the waiting-on: maintainer The ball is in the maintainers’ court label Jul 23, 2026
@tombeckenham
tombeckenham force-pushed the feat/gemini-structured-output-stream branch from 32f4a91 to a259d22 Compare August 10, 2026 09:13
@tombeckenham

Copy link
Copy Markdown
Contributor

Maintainer sweep: rebased onto main (force-with-lease). CI approval handled if it was waiting.

@nx-cloud

nx-cloud Bot commented Aug 10, 2026

Copy link
Copy Markdown

View your CI Pipeline Execution ↗ for commit a259d22

Command Status Duration Result
nx run-many --targets=build --exclude=examples/... ✅ Succeeded 10s View ↗

☁️ Nx Cloud last updated this comment at 2026-08-10 09:28:52 UTC

@pkg-pr-new

pkg-pr-new Bot commented Aug 10, 2026

Copy link
Copy Markdown

Open in StackBlitz

@tanstack/ai

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai@971

@tanstack/ai-acp

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-acp@971

@tanstack/ai-angular

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-angular@971

@tanstack/ai-anthropic

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-anthropic@971

@tanstack/ai-bedrock

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-bedrock@971

@tanstack/ai-byteplus

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-byteplus@971

@tanstack/ai-claude-code

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-claude-code@971

@tanstack/ai-client

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-client@971

@tanstack/ai-code-mode

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-code-mode@971

@tanstack/ai-code-mode-skills

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-code-mode-skills@971

@tanstack/ai-codex

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-codex@971

@tanstack/ai-devtools-core

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-devtools-core@971

@tanstack/ai-durable-stream

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-durable-stream@971

@tanstack/ai-elevenlabs

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-elevenlabs@971

@tanstack/ai-event-client

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-event-client@971

@tanstack/ai-fal

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-fal@971

@tanstack/ai-gemini

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-gemini@971

@tanstack/ai-grok

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-grok@971

@tanstack/ai-grok-build

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-grok-build@971

@tanstack/ai-groq

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-groq@971

@tanstack/ai-isolate-cloudflare

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-isolate-cloudflare@971

@tanstack/ai-isolate-daytona

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-isolate-daytona@971

@tanstack/ai-isolate-node

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-isolate-node@971

@tanstack/ai-isolate-quickjs

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-isolate-quickjs@971

@tanstack/ai-isolate-quickjs-bun

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-isolate-quickjs-bun@971

@tanstack/ai-mcp

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-mcp@971

@tanstack/ai-memory

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-memory@971

@tanstack/ai-mistral

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-mistral@971

@tanstack/ai-ollama

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-ollama@971

@tanstack/ai-openai

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-openai@971

@tanstack/ai-opencode

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-opencode@971

@tanstack/ai-openrouter

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-openrouter@971

@tanstack/ai-persistence

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-persistence@971

@tanstack/ai-preact

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-preact@971

@tanstack/ai-react

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-react@971

@tanstack/ai-react-ui

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-react-ui@971

@tanstack/ai-sandbox

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-sandbox@971

@tanstack/ai-sandbox-cloudflare

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-sandbox-cloudflare@971

@tanstack/ai-sandbox-daytona

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-sandbox-daytona@971

@tanstack/ai-sandbox-docker

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-sandbox-docker@971

@tanstack/ai-sandbox-local-process

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-sandbox-local-process@971

@tanstack/ai-sandbox-sprites

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-sandbox-sprites@971

@tanstack/ai-sandbox-vercel

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-sandbox-vercel@971

@tanstack/ai-solid

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-solid@971

@tanstack/ai-solid-ui

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-solid-ui@971

@tanstack/ai-svelte

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-svelte@971

@tanstack/ai-utils

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-utils@971

@tanstack/ai-vue

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-vue@971

@tanstack/ai-vue-ui

npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-vue-ui@971

@tanstack/openai-base

npm i https://pkg.pr.new/TanStack/ai/@tanstack/openai-base@971

@tanstack/preact-ai-devtools

npm i https://pkg.pr.new/TanStack/ai/@tanstack/preact-ai-devtools@971

@tanstack/react-ai-devtools

npm i https://pkg.pr.new/TanStack/ai/@tanstack/react-ai-devtools@971

@tanstack/solid-ai-devtools

npm i https://pkg.pr.new/TanStack/ai/@tanstack/solid-ai-devtools@971

commit: a259d22

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

waiting-on: maintainer The ball is in the maintainers’ court

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(ai-gemini): native structuredOutputStream for geminiText and geminiTextInteractions

3 participants